.\" Copyright (c) 2014 Jeff Epler
.\"
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" the License, or (at your option) any later version.
.\"
.\" The GNU General Public License's references to "object code"
.\" and "executables" are to be interpreted as the output of any
.\" document formatting or typesetting system, including
.\" intermediate and printed output.
.\"
.\" This manual is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
.\" License along with this manual; if not, write to the Free
.\" Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
.\" USA.
.TH HM2_ETH "9" "2008-05-13" "LinuxCNC Documentation" "HAL Component"
.de TQ
.br
.ns
.TP \\$1
..

.SH NAME

hm2_eth \- LinuxCNC HAL driver for the Mesa Electronics Ethernet Anything IO boards, with HostMot2 firmware.
.SH SYNOPSIS

.HP
.B loadrt hm2_eth [config=\fI"str[,str...]"\fB] [board_ip=\fIip[,ip...]\fB] [board_mac=\fImac[,mac...]\]fB]
.RS 4
.TP
\fBconfig\fR [default: ""]
HostMot2 config strings, described in the hostmot2(9) manpage.
.TP
\fBboard_ip\fR [default: ""]
The IP address of the board(s), separated by commas.  As shipped, the board address is 192.168.1.121.
.SH DESCRIPTION

hm2_eth is a device driver that interfaces Mesa's ethernet
based Anything I/O boards (with the HostMot2 firmware) to the LinuxCNC
HAL.

The supported boards are: 7i76E, 7I80DB, 7I80HD, 7i92, 7i93.

The board must have its hardware loaded on the board by the mesaflash(1) program.

hm2_eth is only available when linuxcnc is configured with "uspace" realtime.

.SH INTERFACE CONFIGURATION

hm2_eth should be used on a dedicated network interface, with only a cable
between the PC and the board.  Wireless and USB network interfaces are not
suitable.

These instructions assume your dedicated network interface is "eth1",
192.168.1/24 is an unused private network, that the hostmot2 board is using the
default address of 192.168.1.121, that you are using Debian 7 or similar, and
that you do not otherwise use iptables.  If any of these are false, you will
need to modify the instructions accordingly.  After following all the
instructions, reboot so that the changes take effect.

It is particularly important to check that the network 192.168.1/24 is not
already the private network used by your internet router, because this is a
commonly-used value.  If you use another network, you will also need to
reconfigure the hostmot2 card to use an IP address on that network by using the
mesaflash(1) utility and change jumper settings.  Typically, you will choose
one of the networks in the
.UR http://en.wikipedia.org/wiki/IPv4#Private_networks
Private IPv4 address space.
.UE
One common alternative is PC address 10.10.10.1, hostmot2 address 10.10.10.10.

Use of the dedicated ethernet interface while linuxcnc is running can cause
violation of realtime guarantees.  hm2_eth will automatically mitigate most
accidental causes of interference.

.SS Configure network with static address
Add these lines to the file /etc/network/interfaces to configure eth1 with a
static address:

.EX
auto eth1
iface eth1 inet static
    address 192.168.1.1
    hardware-irq-coalesce-rx-usecs 0
.EE

.SH PACKET LOSS
While ethernet is fairly resistant to electrical noise, many systems will not
have 100% perfect packet reception.
The hm2_eth driver has a limited ability to deal with lost packets.  Packet
loss is detected by transmitting an expected read or write packet count with
each request, and checking the value with each read response.  When a lost
packet is detected, the
.B packet-error
pin is asserted in that cycle, the
.B packet-error-level
pin is increased, and if it reaches a threshold then a permanent low-level
I/O error is signaled.

However, not all hm2 special functions know how to properly recover from lost
packets.  For instance, the encoder special function does not properly manage
the index feature when packets are lost.  The author believes that this can
lead to rare failures in home-to-index, which can have severe consequences.

On the other hand, pid-stepper systems will run properly for extended periods
of time with packet loss on the order of .01%, as long as following error is
increased enough that having stale position feedback does not trigger a
following error.  Altering the HAL configuration so that during transient
packet loss the pid and motion feedback value is equal to the command value,
instead of the stale feedback value, appears to improve tuning.  This can be
accomplished with a
.B mux2(9)
component for each feedback signal, using
.B packet-error
as the mux2
.B sel
input.

.SH PINS
In addition to the pins documented in
.BR hostmot2(9) ", " hm2_eth(9)
creates additional pins:

.TP
(bit, out) hm2_\fI<BoardType>\fR.\fI<BoardNum>\fR.packet-error
This pin is TRUE when the most recent cycle detected a read or write error,
and FALSE at other times.
.TP
(s32, out) hm2_\fI<BoardType>\fR.\fI<BoardNum>\fR.packet-error-level
This pin shows the current error level, with higher numbers indicating
a greater number of recent detected errors.  The error level is always in
the range from 0 to packet-error-limit, inclusive.
.TP
(bit, out) hm2_\fI<BoardType>\fR.\fI<BoardNum>\fR.packet-error-exceeded
This pin is TRUE when the current error level is equal to the maximum,
and FALSE at other times.

.SH PARAMETERS
In addition to the parameters documented in
.BR hostmot2(9) ", " hm2_eth(9)
creates additional parameters:

.TP
(s32, rw) hm2_\fI<BoardType>\fR.\fI<BoardNum>\fR.packet-error-decrement
The amount deducted from \fIpacket-error-level\fR in a cycle without
detected read or write errors, without going below zero.

.TP
(s32, rw) hm2_\fI<BoardType>\fR.\fI<BoardNum>\fR.packet-error-increment
The amount added to \fIpacket-error-level\fR in a cycle without
detected read or write errors, without going above packet-error-limit.

.TP
(s32, rw) hm2_\fI<BoardType>\fR.\fI<BoardNum>\fR.packet-error-limit
The level at which a detected read or write error is treated as a permament
error.  When this error level is reached, the board's \fIio-error\fR pin
becomes TRUE and the condition must be manually reset.

.TP
(s32, rw) hm2_\fI<BoardType>\fR.\fI<BoardNum>\fR.packet-read-timeout
The length of time that must pass before a read request times out.
If the value is less than or equal to 0, it is interpreted as 80% of the thread
period.  If the value is less than 100, it is interpreted as a percentage of
the thread period.  Otherwise, it is interpreted as a time in nanoseconds.  In
any case, the timeout is never less than 100 microseconds.

Setting this value too low can cause spurious read errors.  Setting it too
high can cause realtime delay errors.


.SH NOTES
hm2_eth uses an iptables chain called "hm2-eth-rules-output" to control access
to the network interface while hal is running.  The chain is created if it does
not exist, and a jump to it is inserted at the beginning of the OUTPUT chain if
it is not there already.  If you have an existing iptables setup, you can insert
a direct jump from OUTPUT to hm2-eth-rules-output in an order appropriate to
your local network.

At (normal) exit, hm2_eth will remove the rules.  After a crash, you can
manually clear the rules with \fBsudo iptables -F hm2-eth-rules-output\fR;
the rules are also removed by a reboot.

"hardware-irq-coalesce-rx-usecs" decreases time waiting to receive a packet
on most systems, but on at least some Marvel-chipset NICs it is harmful.
If the line does not improve system performance, then remove it.  A reboot
is required for the value to be set back to its power-on default.  This
requires the ethtool package to be installed.

.SH BUGS
Some hostmot2 functions such uart are coded in a way that causes additional
latency when used with hm2_eth.

On the 7i92, the HAL pins for the LEDs are called CR01..CR04, but the
silkscreens are CR3..CR6.  Depending on the FPGA firmware, the LEDs may
initially be under control of the ethernet engine.  This can be changed until
power cycle with

.EX
elbpcom 01D914000000
.EE

Depending on firmware version, this driver may cause the hardware error
LED to light even though the driver and hardware are functioning normally.
This will reportedly be fixed in future bitfile updates from Mesa.

.SH SEE ALSO

.BR hostmot2 "(9), " elbpcom (1)
.SH LICENSE

GPL
